home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / ttmedia_load.z / ttmedia_load
Encoding:
Text File  |  2002-10-03  |  13.2 KB  |  198 lines

  1.  
  2.  
  3.  
  4. ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd((((3333))))                                                ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ttmedia_load - send a Display, Edit or Compose request
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<TTTTtttt////ttttttttttttkkkk....hhhh>>>>
  13.      TTTTtttt____mmmmeeeessssssssaaaaggggeeee ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd((((TTTTtttt____mmmmeeeessssssssaaaaggggeeee _c_o_n_t_e_x_t,,,,
  14.                              TTTTttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd____mmmmssssgggg____ccccbbbb _c_b,,,,
  15.                              vvvvooooiiiidddd ****_c_l_i_e_n_t_d_a_t_a,,,,
  16.                              TTTTttttttttkkkk____oooopppp _o_p,,,,
  17.                              ccccoooonnnnsssstttt cccchhhhaaaarrrr ****_m_e_d_i_a__t_y_p_e,,,,
  18.                              ccccoooonnnnsssstttt uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr ****_c_o_n_t_e_n_t_s,,,,
  19.                              iiiinnnntttt _l_e_n,,,,
  20.                              ccccoooonnnnsssstttt cccchhhhaaaarrrr ****_f_i_l_e,,,,
  21.                              ccccoooonnnnsssstttt cccchhhhaaaarrrr ****_d_o_c_n_a_m_e,,,,
  22.                              iiiinnnntttt _s_e_n_d))));;;;
  23.  
  24. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  25.      The ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd() function is used to create and optionally send a Media
  26.      Exchange request to display, edit or compose a document.
  27.  
  28.      The _c_b argument will be passed _c_l_i_e_n_t_d_a_t_a when the reply is received, or
  29.      when intermediate versions of the document are checkpointed through
  30.      _D_e_p_o_s_i_t requests.  The _o_p argument must be one of TTTTTTTTMMMMEEEE____DDDDIIIISSSSPPPPLLLLAAAAYYYY, TTTTTTTTMMMMEEEE____EEEEDDDDIIIITTTT
  31.      or TTTTTTTTMMMMEEEE____CCCCOOOOMMMMPPPPOOOOSSSSEEEE.  The _m_e_d_i_a__t_y_p_e argument names the data format of the
  32.      document, and is usually the primary determinant of which application
  33.      will be chosen to handle the request.  The _c_o_n_t_e_n_t_s and _l_e_n arguments
  34.      specify the document; if they are NNNNUUUULLLLLLLL and zero, respectively, and _f_i_l_e
  35.      is not NNNNUUUULLLLLLLL, then the document is assumed to be contained in _f_i_l_e.  If
  36.      _d_o_c_n_a_m_e is not NNNNUUUULLLLLLLL, then ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd() uses it as the title of the
  37.      document.  If _s_e_n_d is True, the message is sent before being returned.
  38.  
  39.      The _c_o_n_t_e_x_t argument describes the environment to use.  If _c_o_n_t_e_x_t is not
  40.      zero, messages created by ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd() inherit from _c_o_n_t_e_x_t all
  41.      contexts whose slotname begins with the characters EEEENNNNVVVV____.
  42.  
  43.      The TTTTttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd____mmmmssssgggg____ccccbbbb argument is a callback defined as:
  44.  
  45.           TTTTtttt____mmmmeeeessssssssaaaaggggeeee ((((****TTTTttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd____mmmmssssgggg____ccccbbbb))))((((TTTTtttt____mmmmeeeessssssssaaaaggggeeee _m_s_g,,,,
  46.                                             vvvvooooiiiidddd ****_c_l_i_e_n_t_d_a_t_a)))),,,,
  47.                                             TTTTttttttttkkkk____oooopppp _o_p,,,,
  48.                                             uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr ****_c_o_n_t_e_n_t_s,,,,
  49.                                             iiiinnnntttt _l_e_n,,,,
  50.                                             cccchhhhaaaarrrr ****_f_i_l_e))));;;;
  51.  
  52.      The _m_s_g argument is the reply to the load request, or a _D_e_p_o_s_i_t request
  53.      with a _m_e_s_s_a_g_e_I_D argument naming the identifier (see tttttttt____mmmmeeeessssssssaaaaggggeeee____iiiidddd(3)) of
  54.      the load request.  In the latter case, the client program becomes
  55.      responsible for either failing or replying to the request.  In either
  56.      case, _m_s_g should be destroyed after being processed.
  57.  
  58.  
  59.  
  60.  
  61.                                                                         PPPPaaaaggggeeee 1111
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68. ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd((((3333))))                                                ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd((((3333))))
  69.  
  70.  
  71.  
  72.      The _o_p argument is the op of _m_s_g.  It must be either TTTTTTTTMMMMEEEE____DDDDEEEEPPPPOOOOSSSSIIIITTTT or the
  73.      _o_p passed to ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd(3).
  74.  
  75.      The _c_o_n_t_e_n_t_s, _l_e_n and _f_i_l_e arguments represent the contents of the
  76.      arriving document.  If _l_e_n is zero, then the document is contained in
  77.      _f_i_l_e.  If _c_o_n_t_e_n_t_s or _f_i_l_e are non-NNNNUUUULLLLLLLL, they can be freed using
  78.      tttttttt____ffffrrrreeeeeeee().
  79.  
  80.      The _c_l_i_e_n_t_d_a_t_a argument is the _c_l_i_e_n_t_d_a_t_a passed to ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd().
  81.  
  82. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  83.      Upon successful completion, the ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd() function returns the
  84.      request it was asked to build; otherwise, it returns an error pointer.
  85.      The application can use tttttttt____ppppttttrrrr____eeeerrrrrrrroooorrrr(3) to extract one of the following
  86.      TTTTtttt____ssssttttaaaattttuuuussss values from the returned handle:
  87.  
  88.         TTTTTTTT____EEEERRRRRRRR____NNNNOOOOMMMMEEEEMMMM
  89.                 There is insufficient memory available to perform the
  90.                 function.
  91.  
  92.         TTTTTTTT____EEEERRRRRRRR____NNNNOOOOMMMMPPPP
  93.                 The ttttttttsssseeeessssssssiiiioooonnnn(1) process is not running and the ToolTalk
  94.                 service cannot restart it.
  95.  
  96.         TTTTTTTT____EEEERRRRRRRR____OOOOVVVVEEEERRRRFFFFLLLLOOOOWWWW
  97.                 The ToolTalk service has more active messages than it can
  98.                 handle.  (The maximum number of active messages is
  99.                 implementation specific, but is at least 2000.)
  100.  
  101.         TTTTTTTT____EEEERRRRRRRR____PPPPRRRROOOOCCCCIIIIDDDD
  102.                 The specified process identifier is out of date or invalid.
  103.  
  104. AAAAPPPPPPPPLLLLIIIICCCCAAAATTTTIIIIOOOONNNN UUUUSSSSAAAAGGGGEEEE
  105.      After the request created by ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd() is sent, the application will
  106.      probably want to use ttttttttddddtttt____ssssuuuubbbbccccoooonnnnttttrrrraaaacccctttt____mmmmaaaannnnaaaaggggeeee() immediately afterwards to
  107.      manage the standard interactions with the handler of the request.
  108.  
  109.      A TTTTttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd____mmmmssssgggg____ccccbbbb callback should return NNNNUUUULLLLLLLL if it processes _m_s_g
  110.      successfully, or a tttttttt____eeeerrrrrrrroooorrrr____ppppooooiiiinnnntttteeeerrrr() cast to TTTTtttt____mmmmeeeessssssssaaaaggggeeee if processing
  111.      results in an error.  It should return the _m_s_g if it does not consume it,
  112.      in which case the ToolTalk service will pass TTTTTTTT____CCCCAAAALLLLLLLLBBBBAAAACCCCKKKK____CCCCOOOONNNNTTTTIIIINNNNUUUUEEEE down
  113.      the call stack, so that _m_s_g will be offered to other callbacks or (more
  114.      likely) be returned from tttttttt____mmmmeeeessssssssaaaaggggeeee____rrrreeeecccceeeeiiiivvvveeee(3).  Applications will rarely
  115.      want _m_s_g to get processed by other callbacks or in the main event loop.
  116.  
  117. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  118.      This is the typical algorithm of a TTTTttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd____mmmmssssgggg____ccccbbbb:
  119.  
  120.           TTTTtttt____mmmmeeeessssssssaaaaggggeeee
  121.           mmmmyyyyLLLLooooaaaaddddMMMMssssggggCCCCBBBB((((TTTTtttt____mmmmeeeessssssssaaaaggggeeee  mmmmssssgggg,,,,
  122.                   vvvvooooiiiidddd           ****cccclllliiiieeeennnnttttDDDDaaaattttaaaa,,,,
  123.                   TTTTttttttttkkkk____oooopppp         oooopppp,,,,
  124.  
  125.  
  126.  
  127.                                                                         PPPPaaaaggggeeee 2222
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134. ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd((((3333))))                                                ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd((((3333))))
  135.  
  136.  
  137.  
  138.                   uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr  ****ccccoooonnnntttteeeennnnttttssss,,,,
  139.                   iiiinnnntttt             lllleeeennnn,,,,
  140.                   cccchhhhaaaarrrr           ****ffffiiiilllleeee))))
  141.           {{{{
  142.                   iiiiffff ((((lllleeeennnn >>>> 0000)))) {{{{
  143.                           ////**** RRRReeeeppppllllaaaacccceeee ddddaaaattttaaaa wwwwiiiitttthhhh lllleeeennnn bbbbyyyytttteeeessss iiiinnnn ccccoooonnnntttteeeennnnttttssss ****////
  144.                   }}}} eeeellllsssseeee iiiiffff ((((ffffiiiilllleeee !!!!==== 0000)))) {{{{
  145.                           ////**** RRRReeeeppppllllaaaacccceeee ddddaaaattttaaaa wwwwiiiitttthhhh ddddaaaattttaaaa rrrreeeeaaaadddd ffffrrrroooommmm ffffiiiilllleeee ****////
  146.                   }}}}
  147.                   iiiiffff ((((oooopppp ======== TTTTTTTTMMMMEEEE____DDDDEEEEPPPPOOOOSSSSIIIITTTT)))) {{{{
  148.                           tttttttt____mmmmeeeessssssssaaaaggggeeee____rrrreeeeppppllllyyyy((((mmmmssssgggg))));;;;
  149.                   }}}}
  150.                   ttttttttttttkkkk____mmmmeeeessssssssaaaaggggeeee____ddddeeeessssttttrrrrooooyyyy((((mmmmssssgggg))));;;;
  151.                   rrrreeeettttuuuurrrrnnnn 0000;;;;
  152.           }}}}
  153.  
  154. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  155.      TTTTttttttttttttttttkkkk(5), ttttttttmmmmeeeeddddiiiiaaaa____llllooooaaaadddd____rrrreeeeppppllllyyyy(3), ttttttttmmmmeeeeddddiiiiaaaa____ppppttttyyyyppppeeee____ddddeeeeccccllllaaaarrrreeee(3),
  156.      ttttttttmmmmeeeeddddiiiiaaaa____DDDDeeeeppppoooossssiiiitttt(3), tttttttt____ffffrrrreeeeeeee(3), tttttttt____mmmmeeeessssssssaaaaggggeeee____rrrreeeecccceeeeiiiivvvveeee(3).
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                                                                         PPPPaaaaggggeeee 3333
  194.  
  195.  
  196.  
  197.